home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 002 / stf.arc / STF.DOC < prev    next >
Encoding:
Text File  |  1984-11-01  |  7.0 KB  |  177 lines
  1. STF  A DOS Filter to Convert Files to Standard Text Format
  2. =================================================================
  3.  
  4. In my data communications sessions with host computers, bulletin
  5. boards and electronic mail services I work in "text mode" 98% of
  6. the time.  Only the remaining 2% is spent in protocol-controlled
  7. file transfer.
  8.  
  9. Popular asynchronous data communications packages do a poor job
  10. of supporting these work habits.  Specifically, "captured" data
  11. files are not forced to conform to any reasonable conventions.
  12. Anything and everything that comes across the communications
  13. channel ends up in the disk file.  PC-Talk (unmodified),
  14. Crosstalk, Relay and Tymcomm do NOT enforce any conventions and
  15. are all GUILTY!  (It can be argued that this is the appropriate
  16. mode of operation.  Fine, just provide "text mode" rule
  17. enforcement on an optional basis.)
  18.  
  19. Apparently every host computer and RBBS has established its own
  20. unique set of rules for line termination and control character
  21. transmission.  With transparent "data capture" these rules are
  22. propagated to the PC where they make life miserable for
  23. application programs.  Applications performing line-input file
  24. access are surprised to find imbedded ESCape sequences, lines
  25. longer than 254 characters and non-standard line-terminators.
  26.  
  27. In frustration I established my own Standard Text File
  28. conventions.
  29.  
  30. My first approach was to modify PC-TALK.III to include these
  31. rules so that post-processing would not be necessary.  However,
  32. my expanded use of other communications software demanded a
  33. generalized solution.  This is embodied in a DOS filter called
  34. STF (Standard Text Filter) which is designed to post-process
  35. files received by any asynchronous data communication packages.
  36.  
  37. Remember, STF filtering rules apply to disk file data capture.
  38. Communications programs must apply different rules to data
  39. streams destined for the display screen (e.g. ESCape sequences)
  40. or the printer (e.g. Form Feeds).
  41.  
  42.  
  43. STF.PAS
  44. =======
  45.  
  46. STF (Standard Text Filter) provides a conversion between files of
  47. arbitrary content and files conforming to the Standard Text File
  48. definition (see below).
  49.  
  50. It is particularly useful in processing data files captured from
  51. host computers and bulletin board services.  In addition to
  52. creating a predictable output file, STF will convert ASCII device
  53. and paper motion control sequences to printable ASCII characters.
  54.  
  55. STF is written in Turbo Pascal and is on this conference as NOTE
  56. STF.PAS.  A compiled version, NOTE STF.COM (in Tymcomm Image
  57. format), is also available.
  58.  
  59.  
  60. DEFINITIONS
  61. ===========
  62.  
  63. Standard Text File:  A DOS file of Standard Text Lines followed
  64. by an End-of-File marker.
  65.  
  66. Standard Text Line:  Zero to 254 ASCII Graphic Characters
  67. followed by a Carriage Return (X0D) and Line Feed (X0A).
  68.  
  69. ASCII Graphic Character:  Printable ASCII characters in the range
  70. Space (X20) through Tilde (X7E).
  71.  
  72. End-of-File:  A Control-Z (X1A) explicitly marks the end of a
  73. Standard Text File.  A one-character DOS file containing a
  74. Control-Z is a valid Standard Text File.
  75.  
  76. Line Buffer:  An array of 254 characters used to construct the
  77. Standard Text Line.
  78.  
  79. Buffer Pointer:  The position of the last ASCII character
  80. inserted in the Line Buffer.
  81.  
  82. Horizontal Paper Motion:  ASCII control codes determining the
  83. left-to-right position of the next character to be processed.
  84.  
  85. Vertical Paper Motion:  ASCII control codes determining the
  86. top-to-bottom position of the next character to be processed.
  87.  
  88.  
  89. PROCESSING DETAILS
  90. ==================
  91.  
  92. The following chart details the STF filtering actions for each
  93. input character:
  94.  
  95.  
  96. Dec  Hex  Char  Name  Comments
  97. ---  ---  ----  ----  -----------------------------------------
  98.  
  99. 000   00   ^@   NUL   Ignored
  100. 001   01   ^A   SOH   Ignored
  101.   :    :    :         Ignored
  102. 006   06   ^F   ACK   Ignored
  103. 007   07   ^G   BEL   Ignored
  104.  
  105. 008   08   ^H   BS    Horizontal Paper Motion (Backspace):
  106.                       The Buffer Pointer is moved left one
  107.                       position.  Backspacing beyond position 0
  108.                       leaves the Buffer Pointer positioned at 0.
  109.  
  110. 009   09   ^I   HT    Horizontal Paper Motion (Horizontal Tab):
  111.                       The Buffer Pointer is moved right to the
  112.                       next 8-character tab stop (i.e.  9, 17, 25,
  113.                       33, etc.).  Intervening buffer positions
  114.                       are filled with spaces (X20).  Tabbing
  115.                       beyond position 254 leaves the Buffer
  116.                       Pointer positioned at 254.
  117.  
  118. 010   0A   ^J   LF    Vertical Paper Motion (Line Feed):
  119.                       The Line Buffer is written and the Buffer
  120.                       Pointer is set to 0.  See Note 1 below.
  121.  
  122. 011   0B   ^K   VT    Vertical Paper Motion (Vertical Tab):
  123.                       The Line Buffer is written, two zero-length
  124.                       lines are written, and the Buffer Pointer
  125.                       is set to 0.
  126.  
  127. 012   0C   ^L   FF    Vertical Paper Motion (Form Feed):
  128.                       The Line Buffer is written, a line
  129.                       containing '.pa' is written, and the Buffer
  130.                       Pointer is set to 0.
  131.  
  132. 013   0D   ^M   CR    Horizontal Paper Motion (Carriage Return):
  133.                       Ignored:  Vertical Paper Motion is used to
  134.                       detect line-end.
  135.  
  136. 014   0E   ^N   SO    Ignored
  137. 015   0F   ^O   SI    Ignored
  138.   :    :    :         Ignored
  139. 030   1E   ^^   RS    Ignored
  140. 031   1F   ^_   US    Ignored
  141.  
  142. 032   20        SPC   ASCII Graphic         The Buffer Pointer
  143. 033   21   !          ASCII Graphic         is moved right one
  144. 034   22   "          ASCII Graphic         position and the
  145.   :    :   :          ASCII Graphic         character is inserted
  146. 124   7C   |          ASCII Graphic         in the Line Buffer at
  147. 125   7D   }          ASCII Graphic         that position.  See
  148. 126   7E   ~          ASCII Graphic         Note 2 below.
  149.  
  150. 127   7F        DEL   Same as BS  (X08)
  151.  
  152. 128   80              Same as NUL (X00)     A character in the
  153. 129   81              Same as SOH (X01)     range 128-255 is
  154. 130   82              Same as STX (X02)     converted to the
  155.   :    :                                    corresponding
  156. 253   FD              Same as }   (X7D)     character in the
  157. 254   FE              Same as ~   (X7E)     range 000-127.
  158. 255   FF              Same as DEL (X7F)
  159.  
  160. ---  ---  ----  ----  -----------------------------------------
  161.  
  162. Note 1:  The Line Buffer is appended with a Carriage Return and
  163. Line Feed when written.  Additionally, a Control-Z end-of-file
  164. marker is written after the last line in the output file.
  165.  
  166. Note 2:  Line "folding" will occur if the Line Buffer is moved
  167. past position 254 while processing ASCII Graphic Characters.
  168. Line "folding" is accomplished by 1) writing the "full" Line
  169. Buffer, 2) setting the Buffer Pointer to 1, and 3) inserting the
  170. new character in the Line Buffer at position 1.
  171.  
  172. -----
  173.  
  174. Joe Doran
  175.  
  176. *** CREATED 10/26/84 09:02:42 BY $MS ***